plot3D (version 1.0-1)

Perspective box: Creates an empty perspective box, ready for adding objects

Description

perspbox draws a box and labels, and makes space for a colorkey (if any).

Usage

perspbox (x = seq(0, 1, length.out = nrow(z)), 
          y = seq(0, 1, length.out = ncol(z)), z, 
          bty = c("b", "b2", "f", "g", "bl", "bl2", "u", "n"),  ..., 
          col.axis = "black", col.panel = NULL, lwd.panel = 1,                     
          col.grid = NULL, lwd.grid = 1, 
          phi = 40, theta = 40, col = NULL,
          colkey = NULL, plot = TRUE)

Arguments

x, y

Vectors with x and y values. It is sufficient to pass the ranges of the x- and y-values, as they will not be drawn. If z is a matrix, it is required that length(x) = nrow(z) and length(y) = ncol(z).

z

Matrix or vector with z-values. If z is a matrix, it is sufficient to pass a diagonal matrix with the range of the z-values, as they will not be drawn.

bty

The type of the box; only effective if the persp argument box equals TRUE (the default). Unless bty is equal to "u" then the arguments col.axis, c

col.axis, col.panel, col.grid

The color of the axis line, of the axis panel or of the grid lines. Only used if bty = "u".

lwd.panel, lwd.grid

The width of the panel border or of the grid lines. Only used if bty = "u".

theta, phi

The angles defining the viewing direction. theta gives the azimuthal direction and phi the colatitude. see persp.

col

Colors to be used for coloring the colvar variable. Here only used for assessing if a color key should be drawn.

colkey

A logical, NULL (default), or a list with parameters for the color key (legend). List parameters should be one of side, plot, length, width, dist, shift, addlines, col.clab, cex.clab, side.clab, line.clab

plot

Logical. If TRUE (default), a plot is created, otherwise the viewing transformation matrix is returned (as invisible).

...

additional arguments passed to persp. The following persp arguments can be specified: xlim, ylim, zlim, xlab, ylab, zlab, main, sub, r, d, scale, expand, box, ax

Value

• Function perspbox returns the viewing transformation matrix. See trans3D.

Details

The arguments xlim, ylim, zlim only affect the axes. All objects will be plotted, including those that fall out of these ranges. To select objects only within the axis limits, use plotdev. The predefined box types bty are defined as follows: ``f'': all panels are shown and transparent, also the persp default. ``b'': only backward panels shown. ``b2'': as ``b'' with col.grid = "grey". ``g'': only backward panels shown; col.panel = grey(0.95), col.axis = "grey", lwd.grid = 2 and col.grid = "white". ``bl'': only backward panels shown; col.panel = "black", col.axis = "grey", lwd.grid = 2 and col.grid = "white". ``n'': no box is drawn.

See Also

persp3D, scatter2D, surf3D for examples where box types different than the default are used. Hypsometry for an example where colored axis-panels are added to a figure started with perspbox.

Examples

# save plotting parameters                            
 pm   <- par("mfrow")
 pmar <- par("mar")

## ========================================================================
## The 4 predefined box types
## ========================================================================

 par(mfrow = c(2, 2), mar = c(1, 1, 1, 1))
 
# box type with only backward panels
 perspbox(z = volcano, bty = "b", ticktype = "detailed", d = 2, 
          main  = "bty = 'b'")
# box as in 'persp'
 perspbox(z = volcano, bty = "f", ticktype = "detailed", 
          d = 2, main  = "bty = 'f'")

# back panels with gridlines, detailed axes
 perspbox(z = volcano, bty = "b2", ticktype = "detailed", 
          d = 2, main  = "bty = 'b2'")

# ggplot-type, simple axes 
 perspbox(z = volcano, bty = "g", 
          d = 2, main  = "bty = 'g'")

## ========================================================================
## A user-defined box
## ========================================================================

 par(mfrow = c(1, 1))

 perspbox(z = diag(2), bty = "u", ticktype = "detailed", 
          col.panel = "gold", col.axis = "white",  
          scale = FALSE, expand = 0.4, 
          col.grid = "grey", main = "user-defined")

# restore plotting parameters
 par(mfrow = pm)
 par(mar = pmar)